#%RAML 1.0 DataType
description: |

    A buildset gathers build requests that were scheduled at the same time, and which share a source stamp, properties, and so on.

    Update Methods
    --------------

    All update methods are available as attributes of ``master.data.updates``.

    .. py:class:: buildbot.data.buildsets.Buildset

        .. py:method:: addBuildset(scheduler=None, sourcestamps=[], reason='', properties={}, builderids=[], external_idstring=None, parent_buildid=None, parent_relationship=None)

            :param string scheduler: the name of the scheduler creating this buildset
            :param list sourcestamps: sourcestamps for the new buildset; see below
            :param unicode reason: the reason for this build
            :param properties: properties to set on this buildset
            :type properties: dictionary with unicode keys and (source, property value) values
            :param list builderids: names of the builders for which build requests should be created
            :param unicode external_idstring: arbitrary identifier to recognize this buildset later
            :param int parent_buildid: optional build id that is the parent for this buildset
            :param unicode parent_relationship: relationship identifier for the parent, this is a configured relationship between the parent build, and the childs buildsets
            :returns: (buildset id, dictionary mapping builder ids to build request ids) via Deferred

            .. warning:

                The ``scheduler`` parameter will be replaced with a ``schedulerid`` parameter in future releases.

            Create a new buildset and corresponding buildrequests based on the given parameters.
            This is the low-level interface for scheduling builds.

            Each sourcestamp in the list of sourcestamps can be given either as an integer, assumed to be a sourcestamp ID, or a dictionary of keyword arguments to be passed to :py:meth:`~buildbot.db.sourcestamps.SourceStampsConnectorComponent.findSourceStampId`.

        .. py:method:: maybeBuildsetComplete(bsid)

            :param integer bsid: id of the buildset that may be complete
            :returns: Deferred

            This method should be called when a build request is finished.
            It checks the given buildset to see if all of its buildrequests are finished.
            If so, it updates the status of the buildset and sends the appropriate messages.

properties:
    bsid:
        description: the ID of this buildset
        type: integer
    complete:
        description: true if all of the build requests in this buildset are complete
        type: boolean
    complete_at?:
        description: the time this buildset was completed, or None if not complete
        type: integer
    external_idstring?:
        description: |
            an identifier that external applications can use to identify a submitted buildset; can be None
        type: string
    parent_buildid?:
        description: optional build id that is the parent for this buildset
        type: integer
    parent_relationship?:
        description: |
            relationship identifier for the parent, this is a configured relationship between the parent build, and the childs buildsets
        type: string
    reason:
        description: the reason this buildset was scheduled
        type: string
    rebuilt_buildid?:
        description: |
            optional id of a build which was rebuilt or None if there was no rebuild. In case of
            repeated rebuilds, only initial build id is tracked
        type: integer
    results?:
        description: the results of the buildset (see :ref:`Build-Result-Codes`), or None if not complete
        type: integer
    sourcestamps[]:
        description: |
            the sourcestamps for this buildset; each element is a valid :bb:rtype:`sourcestamp` entity
        type: sourcestamp
    submitted_at:
        description:  the time this buildset was submitted
        type: integer
type: object
